\documentstyle[multicol,makeidx,supertabular,vrbinput]{report}

\makeindex

\setlength{\oddsidemargin}{0cm}
\setlength{\evensidemargin}{0cm}
\setlength{\topmargin}{0cm}
\setlength{\textheight}{22cm}
\setlength{\textwidth}{16cm}

\newcommand{\pcs}{{\mediumseries\sc PcScheme}}
\newcommand{\essential}{\marginpar{$\hookleftarrow$}}
\newcommand{\opt}[1]{{\normalshape[}#1{\normalshape]}}
\newcommand{\thunk}[1]{\subsection*{\mediumseries\tt (#1)}\ttindex{#1}}
\newcommand{\esthunk}[1]{\subsection*{\mediumseries\tt (#1)\essential}\ttindex{#1}}
\newcommand{\func}[2]{\subsection*{\mediumseries\tt (#1 \rm\it #2\normalshape\tt)}\ttindex{#1}}
\newcommand{\esfunc}[2]{\subsection*{\mediumseries\tt (#1 \rm\it #2\normalshape\tt)\essential}\ttindex{#1}}

\newcommand{\att}{{\sc Att-400}\index{ATT400@{\sc Att-400}}}
\newcommand{\cga}{{\sc Cga}\index{CGA@{\sc Cga}}}
\newcommand{\mcga}{{\sc Mcga}\index{MCGA@{\sc Mcga}}}
\newcommand{\ega}{{\sc Ega}\index{EGA@{\sc Ega}}}
\newcommand{\herc}{{\sc Hercules}\index{HERCULES@{\sc Hercules}}}
\newcommand{\vga}{{\sc Vga}\index{VGA@{\sc Vga}}}
\newcommand{\ibm}{{\sc Ibm-8514}\index{IBM8514@{\sc Ibm-8514}}}
\newcommand{\hp}{{\sc Hp95lx}\index{HP95LX@{\sc Hp95lx}}}
\newcommand{\svga}{{\sc Super-Vga}\index{SVGA@{\sc Super-Vga}}}

\newcommand{\ttindex}[1]{\index{#1@{\tt #1}}}
\newcommand{\ittindex}[1]{\index{#1@{\itt '#1}}}
\newcommand{\msg}[3]{{\raggedright {\itt '#1\ttindex{#1}} {\it #2} \\ \hfill $\Rightarrow$ {\it #3}}}
\newcommand{\MSG}[2]{{\raggedright {\itt '#1\ttindex{#1}} {\it #2}}}
\newcommand{\List}[1]{{\tt ({\rm\it #1})}}
\newcommand{\Sy}[1]{{\itt '#1}}
\newcommand{\SY}[1]{{\itt '#1}\ittindex{#1}}

\newlength{\entlength}
\newlength{\arrowlead}
\setlength{\arrowlead}{-1.5mm}
\newcommand{\entfont}{\tt}
\newcommand{\ent}[2]{\makebox[\entlength][l]{{\entfont #1}}#2\\}
\newcommand{\res}[2]{\makebox[\entlength][l]{{\entfont
	#1}}\hspace{\arrowlead}$\Longrightarrow$\hspace{2mm}#2\\}
\newcommand{\mess}[3]{\makebox[\entlength][l]{\symb{{#1}} \argt{{#2}}}#3\\}
\newcommand{\mres}[3]{{\addtolength{\entlength}{\arrowlead}%
	\makebox[\entlength][l]{\symb{{#1}}
		\argt{{#2}}\dotfill}$\Rightarrow$\hspace{2mm}{#3}\\}}
\newcommand{\mval}[2]{{\addtolength{\entlength}{\arrowlead}%
	\makebox[\entlength][l]{\symb{{#1}}
		\opt{new-value}\dotfill}$\Rightarrow$\hspace{2mm}{#2}\\}}

\newcommand{\alt}[1]{{\sc Alt-#1}}
\newcommand{\argt}[1]{{\mediumseries\rm\it #1}\/}
\newcommand{\fq}[1]{$\langle${\mediumseries\rm\it #1}$\rangle$}
\newcommand{\ctrl}[1]{{\sc Ctrl\kern1pt-#1}}
\newcommand{\keypad}[1]{\fq{{\sc Keypad #1}}}
\newcommand{\meta}[1]{{\sc Meta\kern1pt-#1}}
\newcommand{\note}[1]{\hspace{1cm}\parbox{10cm}{\raggedright #1}\\}
\newcommand{\Opt}[1]{{\mediumseries\rm\normalshape [}#1{\mediumseries\rm\normalshape ]}}
\newcommand{\shift}[1]{{\sc Shift-#1}}
\newcommand{\symb}[1]{{\it\tt '#1}}
\newcommand{\Proc}[1]{$\lambda${\rm\normalshape ({\rm\it #1}\/)}}

\font\itt=cmitt10
\title{PC Scheme--Geneva:\\User's documentation}
\author{Larry Bartholdi\and Marc Vuilleumier}

\begin{document}
\maketitle
\begin{abstract}
\begin{flushright}
\em ``My English is worse than the garden of my uncle'' \\
---Unknown Chinese philosopher, about 4000 years ago
\end{flushright}
This document describes various major extensions to \pcs\ by the Geneva
Scheme Team. These include BGI, a graphics package based on the
interface developed by Borland\index{Borland}, and Mouse support.
More documentation about {\sc Ed}\index{Ed} will be added here as soon as
available.

BGI is distributed by Borland as C and Pascal\index{Pascal} libraries.
Our adaptation to Scheme preserves the spirit of Borland's original product.

Other documentat about PC~Scheme/Geneva are:
{\bf SCHEME.TEX}, the release log file. You should read it, as it
	contains the most recent informations about PC~Scheme/Geneva;
{\bf REFCARD.TEX}, our Quick Reference Card. It contains all about 
	PC~Scheme/Geneva, including default key sequences for {\sc Edwin}
	and {\sc Ed}.

The authors' work is supported by the University of Geneva.
They can be reached at their E-Mail\index{E-Mail} address ``schemege@cui.unige.ch''.
This document was typeset by \LaTeX.
\end{abstract}

\tableofcontents

\part[Ed: a Generic Editor]{Ed: a Generic Editor\\[1cm]
\setlength{\entlength}{7.2cm}
\sl\normalsize\mediumseries\begin{minipage}{15cm}
\renewcommand{\entfont}{\tt}
\noindent{\sc Ed} is an object-oriented editor toolkit using a subset of 
{\sc Brief}'s key sequences; you can drive it from your programs or
simply use it as a text editor. You can easily remap any key sequence to
any function, or even implement new features.
Basically, {\sc Ed} provides four levels of
editor that you access through four creators (meta-functions):\\[1mm]
\res{(make-editor \opt{window} \opt{\symb{EXIT-FREELY}})}{a basic editor object}
\res{(make-enhanced-editor \ldots)}{ditto, with additional features}
\res{(make-color-editor \ldots)}{ditto, with block highlight}
\res{(make-scheme-editor \ldots)}{ditto, with scheme-specific rules}
\end{minipage}\\[2mm]
\begin{minipage}{15cm}
Typical use:\\
\ent{(define ed (make-\opt{\ldots {\tt-}}editor))}
{; create a full-screen editor}
\ent{(ed \symb{REMAP-KEY} 27 \symb{@GOTO-LINE})}
{; remap {\rm\sc Esc} to ''go to line''}
\ent{(ed \opt{filename})}
{; open the editor}
\end{minipage}\\[1mm]
\begin{minipage}{15cm}
If you want a multi-window editor, you can define two or more editors 
in different window ports; scrapbook and keystroke assignements will be 
shared by all.
\end{minipage}\\[2mm]
\begin{minipage}{15cm}
This part has been written by Marc Vuilleumier.
\end{minipage}
}
%
\chapter{Keystrokes}
\section{Basic Editor Commands}
\newlength{\lrudarrowsize}
\settowidth{\lrudarrowsize}{$\leftrightarrow$}
\setlength{\fboxsep}{1.5pt}
\newcommand{\keyit}[1]{\fbox{#1}}
\newcommand{\sizeup}[1]{\makebox[\lrudarrowsize][c]{#1}}
\newcommand{\lrudarrow}{\sizeup{%
	\makebox[0mm][c]{$\leftrightarrow$}%
	\makebox[0mm][c]{$\updownarrow$}}}
\vspace{1mm}
\begin{tabular}{rclrcl}
\multicolumn{1}{l}{\makebox[18mm][l]{{\bf Step}}}	&
\keyit{$\uparrow$} & \makebox[10mm][l]{} & \multicolumn{1}{l}{\makebox[18mm][l]{{\bf Jump}}}	& \sizeup{{\sc PgUp}} \\
\keyit{$\leftarrow$} & \lrudarrow		& \keyit{$\rightarrow$}	& \ctrl{\keyit{$\leftarrow$}}	& \lrudarrow & \ctrl{\keyit{$\rightarrow$}} \\
					& \keyit{$\downarrow$}	&						&					& \sizeup{{\sc PgDn}} \\[3mm]
\multicolumn{1}{l}{{\large$\mathbf\infty$}} & \sizeup{\ctrl{\sc PgUp}} &	& \multicolumn{1}{l}{{\bf Delete}} \\
{\sc Home}			& \lrudarrow			& {\sc End}				& {\sc BackSpace}	& \lrudarrow & {\sc Del} \\
					& \sizeup{\ctrl{\sc PgDn}} \\
\end{tabular}\\[2mm]
%
\setlength{\entlength}{2.2cm}
\renewcommand{\entfont}{\rm}
\ent{\alt I}{toggle \underline insert/overwrite mode}
\ent{\alt G}{\underline go to line}
\ent{\alt K}{\underline kill to end of line}
\ent{\alt D}{\underline delete current line}
\ent{\ctrl L}{refresh display}
\ent{\sc F7}{record a keystroke sequence}
\ent{\sc F8}{replay a keystroke sequence}
\ent{\sc F10}{execute a command by name}[1mm]
\ent{\alt E}{\underline edit another file}
\ent{\alt W}{\underline write file to disk}
\ent{\alt O}{choose new \underline output name}
\ent{\alt R}{\underline read a file into current}
\ent{\alt X}{e\underline xit editor}
\vfil\newpage
%
\section{Enhanced Editor Commands}
Use a Color Editor if you want block highlight features.\\[1mm]
\ent{\alt M}{\underline mark block}
\ent{\alt L}{\underline line block}
\ent{\alt C}{\underline column block}
\ent{\keypad{$-$}}{cut block/line to scrap}
\ent{\keypad{$+$}}{copy block/line to scrap}
\ent{\keypad{$/$}}{invert block bounds (swap anchor)}
\ent{\sc Ins}{insert scrap into text}
\ent{\sc Del}{delete block}
\ent{\alt W}{\underline write block/file to disk}[1mm]
\ent{\alt{{\normalshape [}$1\ldots 3${\normalshape ]}}}{drop a bookmark}
\ent{\alt J {\normalshape [}$1\ldots 3${\normalshape ]}}{\underline jump to bookmark}
\ent{\ctrl R}{\underline replicate a command}[1mm]
\ent{\ctrl{\sc F5}}{toggle case sensivity}
\ent{\alt S or {\sc F5}}{\underline search string}
\ent{\shift{\sc F5}}{repeat previous search}
\ent{\alt T or {\sc F6}}{\underline translate string}
\ent{\shift{\sc F6}}{repeat previous translate}

\section{Scheme Editor Commands}
Autoindent is active and color changes on each parenthesis level.\\[1mm]
\ent{\ctrl A}{enlarge mark around Scheme expression}
\ent{\ctrl Z}{mark the biggest Scheme expression}
\ent{\ctrl{\sc F10}}{evaluate marked expression}
\ent{\alt{\sc F10}}{evaluate current file}
\ent{\sc Tab}{complete symbol or reindent line/block}
\ent{\shift{\sc Tab}}{prepare to add a comment}
\ent{\alt Q \fq{key}}{use \argt{key}'s basic definition}

\chapter{Driving an Editor}
\setlength{\entlength}{6cm}
\vspace{-7.5ex}
\renewcommand{\entfont}{\tt}
\ent{(ed \opt{message} \opt{arguments})}{\argt{message} defaults to
\symb{OPEN}}
\mess{OPEN}{\opt{filename}}{pop-up the editor, handle commands}
\mess{SAFE}{}{ensure current buffer is saved}
\mess{CLEAR}{}{clear buffer}
\mval{NAME}{name of buffer}
\mval{BUFFER}{a list of strings}
\mval{POSITION}{cursor position}
\mval{INSERT}{{\tt \#F} when in overwrite mode}
\mval{TAB}{tab expansion width}
\mval{TABULIZE-MODE}{\symb{COMPRESS}, \symb{NORMAL} or \symb{EXPAND}}
\mval{SEPARATORS}{string (used for word move)}
\mval{CASE-SENSIVITY}{{\tt \#F} when disabled}
\mval{COLORS}{associative color list}
\mval{COMMENT-COLUMN}{column \#}
\mval{INDENT-TOKENS}{list of special tokens}
\mval{INPUT-PORT}{port used for input}
\mess{DO-STRING}{string}{feed editor with keystrokes}
\mres{READ-ACTION}{}{an \argt{action}: the next event}
\mess{HANDLE-ACTION}{action}{process one command}
\mess{REMAP-KEY}{key function}{}
\note{\argt{key} is {\tt (list* \opt{\ldots\ {\sc Ascii}$_2$} 
	\argt{{\sc Ascii}$_1$})}}
\note{\argt{function} if {\tt (list* \opt{\List{context action} \ldots} 
	\argt{default-action})}}
\note{\argt{context} is \Proc{ed} $\longrightarrow$ boolean}
\note{\argt{action} is a character, a string, or a symbol:}
\hbox{\hspace{3mm}\vrule
\setlength{\tabcolsep}{0mm}
\begin{tabular}{llll}
\makebox[.23\textwidth][l]{\symb{@LEFT}} &
\makebox[.23\textwidth][l]{\symb{@WORD-LEFT}} &
\makebox[.25\textwidth][l]{\symb{@HOME}} &
\makebox[.23\textwidth][l]{\symb{@RIGHT}} \\
\symb{@WORD-RIGHT} &
\symb{@END} &
\symb{@UP} &
\symb{@PAGE-UP} \\
\symb{@TOP-OF-BUFFER} &
\symb{@DOWN} &
\symb{@PAGE-DOWN} &
\symb{@END-OF-BUFFER} \\
\symb{@DEL} &
\symb{@DELETE-TO-EOL} &
\symb{@DELETE-LINE} &
\symb{@BACKSPACE} \\
\symb{@TAB} &
\symb{@ENTER} &
\symb{@QUOTE} \\[1mm]
\symb{@INSERT-MODE} &
\symb{@GOTO-LINE} &
\symb{@REFRESH} &
\symb{@RECORD} \\
\symb{@PLAY} &
\symb{@EXECUTE} &
\symb{@LOAD} &
\symb{@READ-INTO} \\
\symb{@WRITE} &
\symb{@RENAME} &
\symb{@EXIT} \\[1mm]
\symb{@SEARCH} &
\symb{@REPEAT-SEARCH} &
\symb{@CASE-SENSITIVITY} &
\symb{@TRANSLATE} \\
\symb{@REPEAT-TRANSLATE} &
\symb{@REPLICATE} &
\symb{@BOOKMARK-\opt{{\bf 1\ldots3}}} &
\symb{@JUMP-TO-\opt{{\bf 1\ldots3}}} \\[1mm]
\symb{@MARK-BLOCK} &
\symb{@LINE-BLOCK} &
\symb{@COLUMN-BLOCK} &
\symb{@CUT-BLOCK} \\
\symb{@COPY-BLOCK} &
\symb{@INSERT-BLOCK} &
\symb{@CANCEL-BLOCK} &
\symb{@SWAP-ANCHOR} \\[1mm]
\symb{@MARK-EXPR} &
\symb{@MARK-DEF} &
\symb{@SCHEME-PARENTHESIS} &
\symb{@COMPLETION} \\
\symb{@INDENT} &
\symb{@COMMENT} &
\symb{@EVAL} &
\symb{@EVAL-BLOCK} \\
\symb{@SCHEME-ENTER} \\
\end{tabular}
}

\part[Mouse Support in \pcs]{Mouse Support in \pcs\index{Mouse}\\[1cm]
\sl\normalsize\mediumseries\begin{minipage}{15cm}
Microsoft(TM)\index{Microsoft} specified a standard interface to drive
the mouse from within applications. Practically all mouse vendors
adhered to this interface, so it made sense to access the mouse
though it from within \pcs. Unfortunately, the standard was designed for
interfacing to assembly language and thus contains some peculiarities,
like event handlers, that have carefully to be dealt with.
\end{minipage}\\[2mm]
\begin{minipage}{15cm}
The solution proposed is a slight extension of \pcs's core---the
virtual machine. An op-code has been added to support the {\tt int~33h}
calls, as well as an assembly-language event handler that dispatches
requests to a Scheme closure. The solution is not perfect in the sense
event handling cannot be honored in the middle of a basic instruction
(for instance, during a call to {\tt readline}). The slowdown due to
Scheme handling of even the most simple events (like recording a move),
and the context switching required, may render event handling
unpractical on slow processors; the system has nevertheless successfully
been used on a fast 80486 PC.
\end{minipage}\\[2mm]
\begin{minipage}{15cm}
This part has been written by Larry Bartholdi.
\end{minipage}
}

\chapter{The interfacing}
The most important differences between the assembly level interface
and the Scheme procedures are:
\begin{itemize}
\item	\pcs\ has an Object-Oriented interface
\item	\pcs\ uses symbolic constants abundantly (and list of constants
	instead of bit masks)
\end{itemize}

On the lowest level, all requests are executed through
\func{\%MOUSE}{ax bx cx dx si di \opt{es:dx}}
which returns a list: \List{ax bx cx dx} of the CPU registers after
the call has been effected. Fortunately you will never have to call this
function directly; but this is how \pcs's interface works.

The high-level interface (in {\tt MOUSE.FSL}) works with a single ``mouse''
object,
\esfunc{MOUSE}{message \opt{parameters}}
that translates the message to {\tt (\%mouse)} calls. The messages {\tt mouse}
recognises are:
\vspace{5mm}
\tablehead{\multicolumn{1}{c}{{\bf Message Args} $\Rightarrow$ {\bf Result}}
	& {\bf Comments} \\ \hline \\[2mm]}
\tabletail{}

\newlength{\oldindent}
\setlength{\oldindent}{\parindent}
\setlength{\parindent}{0cm}
\begin{supertabular}{p{5cm}|p{10.4cm}}
\msg{RESET}{}{\#-buttons}	& This message should be the first
	sent when dealing with the mouse. It returns $-1$ if no mouse is
	avaliable. \\
\MSG{SHOW}{}	&	Increments the mouse's visibility count. The count
	initially is $-1$, can be incremented or decremented, but can never
	become positive (calls to \SY{SHOW} are without effect if the count
	is ${} \ge 0$). The pointer is visible only when the count is $= 0$. \\
\MSG{HIDE}{}	&	Decrements the mouse's visiblity count. \\
\msg{INQ}{}{\List{buttons-down x y}}	& {\it buttons-down}
	is a list containing any of \SY{LEFT}, \SY{RIGHT} and {\itt CENTER}.
	The x-- and y-positions are thought in $640\times200$ units, although
	they can be redefined to any scaling. They are always in linear
	correspondence with the ``Mickeys''. \\
\MSG{MOVE}{x y} &	Moves the pointer to an absolute location. As always,
	$(0,0)$ is the upper left corner. The values are clipped to the
	limiting rectangle. \\
\msg{PRESS}{button}{\List{buttons-down count x y}} &
	There is an additional field compared to \SY{INQ}: the number of
	times the button has been pressed. All other values refer to
	the mouse state when the last ``press'' occured. The count is reset
	to 0 after this call.

	{\it button} is a symbol.\\
\msg{RELEASE}{button}{\List{buttons-down count x y}} &
	Just like \SY{PRESS}, except it returns the release count. \\
\MSG{LIMITS}{\SY{HORIZONTAL} $x_0$ $x_1$}	& Sets the mouse's horizontal
	viewport. It will not be able to move out of that area. If it is
	outside at the moment of the call, it will be projected to the border. \\
\MSG{LIMITS}{\SY{VERTICAL} $y_0$ $y_1$} & Sets the mouse's vertical viewport. \\
\MSG{LIMITS}{\SY{BOTH} $x_0$ $x_1$ $y_0$ $y_1$} & Sets the mouse's viewport. \\
\MSG{SHAPE}{shape} & Sets the graphics pointer. {\it shape} is a list:
	\List{x-hot-spot y-hot-spot and-mask xor-mask}, where the masks
	are lists of 16 integers. This function does not affect the text-mode
	pointer. \\
\msg{CURSOR}{name}{cursor} & Returns a predefined pointer for \Sy{SHAPE}.
	Two sources were used to grab bitmapped pointers: the X Windows
	shared library (in {\tt openwin/share/lib/include/bitmaps}), and
	an {\sc MsDos} package called ``Precise Point''. Both sources were
	used without permission.

	{\it name} is a symbol, and can have values
\SY{CENTER}, \SY{KEYBOARD}, \SY{LEFT}, \SY{RIGHT}, \SY{STAR6}, \SY{TARGET}
(X Windows) and
\SY{ARROW}, \SY{BLOCK}, \SY{CIRCLE}, \SY{EXCLAIM}, \SY{HAND}, \SY{HOURGLAS},
\SY{KITE}, \SY{MESH}, \SY{SMALL}, \SY{SQUARE}, \SY{STAR4}, \SY{TEXT}, \SY{X}
(Precise Point). \\

\MSG{TEXT-TYPE}{\SY{SOFTWARE} and xor} & Sets the text-mode pointer to
	software, i.e.\ to modification of characters on the screen.
	{\it and} and {\it xor} are pairs: \List{character .\ attribute}.
	As a simple example,
	\begin{verbatim}
(mouse 'TEXT-TYPE 'SOFTWARE
       (cons (integer->char \#xff) \#xff)
       (cons (integer->char 0) \#x80))}
	\end{verbatim}
	would make the character under the pointer blink. \\
\MSG{TEXT-TYPE}{\SY{HARDWARE} start end} & Sets the text-mode pointer to
	hardware, i.e.\ uses the cursor generator of the graphics adapter.
	{\it start} and {\it end} are the start-- and end-rows of the cursor,
	usually in range 0--8 or 0--16. Note that the cursor then serves two
	uses; this mode should be useful especially in an editor, if the
	mouse moves are interpreted as cursor positioning. \\
\msg{MICKEYS}{}{\List{x y}} & Returns the mouse's movement in Mickeys
	since the previous call to this function. A Mickey\index{Mickey} is
	the mouse's fundamental unit, $\approx 1/200\mbox{inch}$. \\
\msg{HANDLER}{handler}{old-handler} &	Installs an event handler.
	A handler is a list: \List{events .\ procedure}, where {\it events} is
	a list containing any of \SY{MOVE}, \SY{LEFT-DOWN}, \SY{LEFT-UP},
	\SY{LEFT} (both left-button messages), \SY{RIGHT-DOWN}, \SY{RIGHT-UP},
	\SY{RIGHT}, \SY{CENTER-DOWN}, \SY{CENTER-UP}, \SY{CENTER}, \SY{DOWN},
	\SY{UP}, and \SY{BUTTONS}.
	When one of these events occurs, {\it procedure} will be called.
	{\it procedure}'s arguments are \List{triggering-events buttons-down
	x y mickeys-x mickeys-y event-time}. Note that {\it triggering-events}
	is a list, because it may contain more than one event.

	An important thing to mention is that normally {\it procedure} will
	not be reinvoked before it returns. Events that occur during {\it
	procedure}'s execution are lost. In particular, if {\it procedure}
	does not return (in case of error, for instance), mouse events
	remain disabled. They can be re-enabled with the next command. \\
\MSG{ENABLE}{} & Re-enables event handling. With this, re-entrant
	mouse-handlers can be written! 

	In its normal operating mode, {\tt mouse} stacks up mouse messages
	and dispatches them one at a time, sending the next message when the 
	dispatch of the previous one returned. If this function is called, the
	message-dispatching system is spawned; in effect, calling this function
	from within an event handler may result in the handler being called
	``re-entrantly''. \\
\MSG{DISABLE}{} & This message suppresses re-entrancy by cancelling the
	effect of a previous \Sy{ENABLE}. \\
\MSG{PEN-ON}{} & Microsoft Manual says ``{\bf Light-Pen emulation:} Enables light
	pen emulation by the mouse driver for IBM BASIC. A ``pen down'' condition
	is created by simultaneously pressing the left and right mouse buttons.''
	I tried darn hard to understand this, without success. \\
\MSG{PEN-OFF}{} & ditto. \\
\MSG{MICKEY-RATIO}{x y} & Sets the number of Mickeys per 8 pixels for
	horizontal and vertical mouse motion. \\
\MSG{EXCLUDE}{$x_0$ $x_1$ $y_0$ $y_1$} & Defines a rectangle within which
	the mouse is invisible. \\
\MSG{SPEED-THRESHOLD}{speed} & Sets the speed limit between simple--
	and double-speed motion, in Mickeys per second. \\
\msg{SENSITIVITY}{[x y speed]}{\List{x y speed}} & Reads or sets
	the Mickey ratio and speed threshold. \\
\MSG{INTERRUPT-RATE}{rate} & {\it rate} can be \Sy{NONE}, 30, 50, 100
	or 200, and governs the tradeoff between graphic resolution and
	application performance. It is applicable only to the {\sc InPort}
	mouse\index{InPort} (see \Sy{INFORMATION}). \\
\msg{POINTER-PAGE}{[page]}{page} & Reads or sets the display page for the
	mouse pointer. \\
\msg{LANGUAGE}{[language]}{language} &	Reads or sets the language for mouse
	driver messages. {\it language} can be any of \Sy{ENGLISH}, \Sy{FRENCH},
	\Sy{DUTCH}, \Sy{GERMAN}, \Sy{SWEDISH}, \Sy{FINNISH}, \Sy{SPANISH},
	\Sy{PORTUGESE} or \Sy{ITALIAN}. \\
\msg{INFORMATION}{}{\List{version type IRQ}} &
	Returns information on the mouse driver. {\it version} is a floating-point
	number. {\it type} is a symbol: \Sy{BUS}, \Sy{SERIAL}, \Sy{INPORT},
	\Sy{PS/2} or \Sy{HP}. {\it IRQ} is an integer. \\
\end{supertabular}
\setlength{\parindent}{\oldindent}

\chapter{A simple example}
I include here a simple demo of what can be done with graphics and mouse:
a program that draws lines at random while the pointer (representing
two eyes) winks at the user when he presses the buttons.
{\small\verbatiminput{../samples/eyes.s}}

\part[BGI: The Graphics Package]{BGI:
The Graphics Package\\
{\sl\normalsize\mediumseries Written by Marc Vuilleumier}\\
{\sl\normalsize\mediumseries Last change October 5, 1993. First draft November 27, 1992}}

\chapter{User's manual}

\section{What is BGI?}
BGI\index{BGI} is a powerful, standard, device-adaptable interface for graphic output.
It was introduced by Borland\index{Borland} compilers, and give programmers a complete
set of graphic primitives, working on every device for which a BGI driver\index{driver}
exist. Included with this version of \pcs, you'll find drivers for
\cga, \mcga, \att, \ega, \vga, \herc, \ibm, {\sc Pc-3270}, \hp\ and true compatibles\index{compatibility}.

You may use any other BGI driver found on public sites or provided by
your graphic hardware vendor (such as the {\tt SVGA.BGI\index{BGI@.BGI}} driver for
\svga\ designed for Borland\index{Borland} C 3.0 to improve the resolution\index{resolution}
and color\index{color} capabilities.

You may also use the two drivers one of us (lb) has written,
that are distributed with \pcs: {\tt SPY.BGI}\index{SPY} and {\tt PS.BGI}.
The former is a debugging\index{debugging} aid that prints
to the screen all the driver requests. The latter creates a PostScript\index{PostScript}
document\index{document} that can then be incorporated in a text processor or sent to
a printer\index{printer}. See section~\ref{sec:drivers} for more information.

\section{What is different in \pcs's implementation of BGI?}
\begin{itemize}
\item	The name of primitives and constants\index{constants} is ``Scheme-like''
	splitted in words:
	\begin{center}
	\begin{tabular}{lcl}
	{\bf Borland C 3.0}	& &	\pcs \\[1mm]
	{\tt initgraph(...)\index{initgraph(\ldots)}}	& $\Longrightarrow$ &	{\tt (init-graph ...)} \\
	{\tt setcolor({\itt LIGHTBLUE})} & $\Longrightarrow$ & {\tt (set-color\ttindex{SET-COLOR} \SY{LIGHT-BLUE})}
	\end{tabular}
	\end{center}
\item	Since graphic constants are contextual (which is not the case in C),
	we have removed redundancy in symbol\index{symbol!redundancy} names:
	\begin{center}
	\begin{tabular}{lcl}
	{\bf Borland C 3.0}	& &	\pcs \\[1mm]
	{\tt setlinestyle({\itt DOTTED\_LINE}, ...)} & $\Longrightarrow$ &
		{\tt (set-line-style\ttindex{SET-LINE-STYLE} \SY{DOTTED} ...)} \\
	{\tt settextstyle({\itt GOTHIC\_FONT}\index{font!gothic}, {\itt HORIZ\_DIR}, 4)} &
		$\Longrightarrow$ & {\tt (set-text-style\ttindex{SET-TEXT-STYLE} \SY{GOTHIC}
		{\itt HORIZ} 4)}
	\end{tabular}
	\end{center}
\item	Some parameters are optional\index{arguments!optional}. The following commands, for instance,
	are all equivalent:
	\begin{center}
	\begin{flushleft}
	{\tt (init-graph \SY{DETECT} 0 "")} \\
	{\tt (init-graph \SY{DETECT} 0)} \\
	{\tt (init-graph \SY{DETECT})} \\
	{\tt (init-graph)}
	\end{flushleft}
	\end{center}
\item	Static structures have been replaced by lists\index{lists}.
	For instance, a polygon\index{polygon} is not an integer and an array,
	but simply a list of points\index{point}.
\item	The coordinate\index{coordinate} system can be completely adapted by the user.
\item	Twin-functions returning X and Y values have been joined and produce
	a point (i.e.\ a pair). This is true for text measurement, too.
\item	Special memory allocation functions have not been included.
\end{itemize}

\section{Coordinate systems}\index{coordinate}
Most graphic primitives have to place objects, on the screen for instance,
given some coordinates; we call a ``point\index{point}'' the information
necessary to explicit a location on the output device.

By default, a point\index{point} is a pair of whole numbers, the X and Y coordinates,
and therefore it is highly device-dependent: using a Color Graphic Adapter
(\cga) mode\index{mode!graphics}, for instance, the valid coordinate range is
\Sy{(0 .\ 0)} through \Sy{(319 .\ 199)} in 4-color\index{color!4-color} mode,
and \Sy{(0 .\ 0)} and \Sy{(639 .\ 199)} in Black\&White mode.
With a Hercules-monochrome adapter, the range becomes
\Sy{(0 .\ 0)} through \Sy{(719 .\ 347)}, and so on; \Sy{(0 .\ 0)} is 
always the upper left corner of the screen, contrary to mathematical
tradition. Note that BGI routines usually clip\index{clipping} their parameters to
the screen rectangle.

Now \pcs\ allows you to freely define the coordinate system you'd like to
use. You only need to specify the desired coordinates of the upper left 
and bottom right corner, no matter which video adapter or other device
is present. A typical sequence would be:
\begin{center}
\begin{tabbing}
{\tt (set-world! \Sy{(-100 .\ -100)} \Sy{(100 .\ 100)})}	\= \kill
{\tt (init-graph)}	\> ; detect and initialize video adapter \\
{\tt (set-world! \Sy{(-100 .\ -100)} \Sy{(100 .\ 100)})}
	\> ; set the screen coordinates with origin centered \\
{\tt (put-pixel\index{pixel} \Sy{(0 .\ 0)} \SY{BLUE})}
	\> ; plot\index{plot} a blue pixel at center of screen
\end{tabbing}
\end{center}

Note that the X and Y coordinates are now real numbers,
so you are allowed to call {\tt SET-WORLD!\index{SET-WORLD@{\tt SET-WORLD"!}}} with parameters like:
\begin{center}
\begin{tabbing}
{\tt (set-world! `((- ,pi\index{pi}) .\ 1) `(,pi .\ -1))} ; ideal to plot a sine\ldots\index{plot}
\end{tabbing}
\end{center}

Of course, if you need to scan every pixel, you can use {\tt GET-MAX-XY}
\ttindex{GET-MAX-XY} to obtain
the actual resolution\index{resolution} of your screen adapter.

If you are urging to try BGI by yourself, skip to part~\ref{reference},
page~\pageref{reference}.
What follows is an extension to the BGI standard.

\section{And further\ldots}
For type checking of point\index{point} parameters, you are allowed to use the
{\tt SET-POINT?-!\index{SET-POINT@{\tt SET-POINT?-"!}}} primitive to change the point type.
For instance, the following code would allow points to be
a pair of real (this is done automatically when you use {\tt SET-WORLD!}).
\begin{center}
\begin{tabbing}
\verb+(define (real-point point)+	\= ; Type-checking for points\index{point} \\
\verb+  (and (pair? point)+ \\
\verb+       (number? (car point))+ \\
\verb+       (number? (cdr point))))+ \\
\verb++ \\
\verb+(set-point?-! real-point)+	\> ; Use the real-coordinates system
\end{tabbing}
\end{center}

Now imagine you want to draw a bar chart using an exponential\index{exponential} scale.
Instead of adding a call to the LOG function before each
call to BGI routine, you can define your own coordinates-conversion
function. Call {\tt SET-COORDINATES!\index{SET-COORDINATES@{\tt SET-COORDINATES"!}}} with
three functions as parameters, one extracting the device's
X-coordinate from a point\index{point}, one extracting the Y-coordinate,
and the reverse procedure which returns the point corresponding
to given device coordinates:
\begin{center}
\begin{tabbing}
\verb+(set-coordinates! my-x my-y reverse-xy)+ \= \kill
\verb+(define (my-x point)+	\> ; X-coord scaled from 0 to 1 \\
\verb+  (round+			\> ; Return a whole number \\
\verb+    (* (car point)+	\> ; Multiply the given X-coordinate\ldots\\
\verb+       (car (get-max-xy)))))+ \> ; \ldots by the maximum X-coordinate\ttindex{GET-MAX-XY} \\
\verb++ \\
\verb+(define (my-y point)+	\> ; Y-coord log: 1 (bottom) to 1000 \\
\verb+  (round+			\> ; Return a whole number  \\
\verb+    (* (- 1 (log (cdr point) 1000))+ \> ; Log of reversed y-coordinate\ldots\\
\verb+       (cdr (get-max-xy)))))+ \> ; \ldots times the maximum y-coordinate \\
\verb++ \\
\verb+(define (reverse-xy xy)+	\> ; Reverse procedure, used when BGI \\
\verb+  (let ((max-xy (get-max-xy)))+ \> ; wants to return a coordinate \\
\verb+    (cons+		\> ; Return a point (a pair) \\
\verb+      (/ (car xy) (car max-xy))+ \\
\verb+      (expt 1000 (- 1 (/ (cdr xy) (cdr max-xy)))))))+ \\
\verb++ \\
\verb+(set-coordinates! my-x my-y reverse-xy)+ \> ; Use the vertical-logarithmic system
\end{tabbing}
\end{center}

Don't forget to call {\tt SET-POINT?-!}, because {\tt SET-COORDINATES!}
won't call it for you (the example above assumes you've already typed in
the {\tt SET-POINT?-!} example).

Note that using this coordinate system, the same call to a function such
as LINE-REL\ttindex{LINE-REL} can have different results, depending on where the pen\index{pen} is:
\begin{center}
\begin{tabbing}
{\tt (move-to \Sy{(0.5 .\ 100)})} \= \kill
{\tt (move-to \Sy{(0.5 .\ 1)})} \\
{\tt (line-rel \Sy{(0 .\ 10)})} \> ; length = 1/3 of total height \\
\verb++ \\
{\tt (move-to \Sy{(0.5 .\ 100)})} \> ; goes up into log scale\ldots\ttindex{MOVE-TO}\\
{\tt (line-rel \Sy{(0 .\ 10)})} \> ; length = 1/72 of total height
\end{tabbing}
\end{center}

Of course, you don't need to assume that a point\index{point} is a pair; why not a list
of numbers, in a three- or four-dimensional space? Just write the functions
that extract a projection\index{projection} out of a vector, and you're done!

Do you like Euclid\index{Euclid}? If you don't, you can also define
how to calculate distances\index{distance}, almost the same way you
defined the coordinates. {\tt SET-DISTANCES!\index{SET-DISTANCES@{\tt SET-DISTANCES"!}}} accepts
three parameters: the X distance extractor,
the Y distance extractor and the unary distance\index{distance!unary} extractor.
These three functions receive the point\index{point} from which the distance
is to be calculated and the user-desired distance.
X \& Y distances are used for the following functions:
{\tt MOVE-REL\ttindex{MOVE-REL}}, {\tt LINE-REL\ttindex{LINE-REL}}, {\tt ELLIPSE\ttindex{ELLIPSE}}, {\tt FILL-ELLIPSE\ttindex{FILL-ELLIPSE}}
and {\tt SECTOR\ttindex{SECTOR}}, while the unary distance is used by
{\tt ARC\ttindex{ARC}}, {\tt CIRCLE\ttindex{CIRCLE}} and {\tt PIE-SLICE\ttindex{PIE-SLICE}}
(``unary'' means that the function receives distances as a number
and returns a number; while X and Y distances receive a fictive point\index{point}
which is the displacement\index{displacement} between two points\index{point}).

All these coordinate-manipulation primitives return
the previous version of all the procedures they change,
so you can restore them later.
In particular, SET-WORLD! returns all of seven procedures,
in the order {\tt POINT?\ttindex{POINT?}, X, Y, REVERSE-XY, X-DIST, Y-DIST, {\rm and} UNARY-DIST};
and all can be restored in one single call to {\tt RESTORE-WORLD!\index{RESTORE-WORLD@{\tt RESTORE-WORLD"!}}}:
\begin{center}
\begin{tabbing}
{\tt (let ((old-sys (set-world! \Sy{(0 .\ 0)} \Sy{(1 .\ 1)})))} ; change and remember \\
\verb+  ...+ \\
\verb+  (restore-world! old-sys))+
\end{tabbing}
\end{center}

If you want to restore procedures by yourself, note the following example:
\begin{center}
\begin{tabbing}
{\tt (let* ((old-sys (set-world! \Sy{(0 .\ 0)} \Sy{(1 .\ 1)}))}	; change and remember \\
\verb+	(old-point? (car old-sys))+ \\
\verb+	(old-coord (cdr old-sys))+ \\
\verb+	(old-dist (cdddr old-coord)))+ \\
\verb+  ...+ \\
\verb+  (set-point?-!     old-point?)+ \\
\verb+  (set-coordinates! (car old-coord) (cadr old-coord) (caddr old-coord))+ \\
\verb+  (set-distances!   (car old-dist)  (cadr old-dist)  (caddr old-dist))+ \\
\end{tabbing}
\end{center}

Always restore procedures in this order, since {\tt SET-COORDINATES!} modifies
the distance-functions to adapt them to the new given system.

\section{The PS and SPY\index{SPY} drivers}\label{sec:drivers}
{\centering\sl This part has been written by Larry Bartholdi.}

One one the restrictions of BGI was that it could handle displays,
but not printers\index{printer}. To overcome this limitation, some people developed
``printer packages'' for BGI. Although they derive from a real need,
they are almost useless in that the force a complete re-write of the
high-level code, linking with extra libraries, etc. By contrast, the
solution I propose is a simple ``plug-and-play\index{plug-and-play}'': the driver
should be recoginsed by any system using BGI that allows user-supplied
drivers\index{drivers!user-supplied} to be installed
(see {\tt INSTALL-USER-DRIVER\ttindex{INSTALL-USER-DRIVER}}).
The price to pay is, of course, that the driver produces only PostScript\index{PostScript}
output. This postScript can then be send to a laser\index{printer!laser} printer, inserted
in a text document, or converted to another format or device. See for
instance GNU\index{GNU}'s ``ghostscript\index{ghostscript}''.

The drivers are written in C. This makes them very easy to change,
while requiring very little extra space. An interface to the C code,
written in assembly language is provided. Users are free to write their
own BGI drivers using this system.

\subsection{How to use SPY}
SPY is really a very simple driver, that was written mostly to debug
the C interfacing (whence the name). It has only one mode\index{mode!SPY}, 1 color\index{color}
(really two---black and white) and a fictive resolution\index{resolution} of $100\times100$.
All it does is write the graphics requests it receives to the standard
output.

\subsection{How to use PS}
PS basically operates like SPY: it translates graphics requests to
text, which it then writes to a file (or the standard output if none
is specified). The environment\index{environment} variable ``\verb+PS$+\index{PS\$}'' specifies on
which file the output should go. Beware that the variable cannot be
changed from within \pcs. This is a strange behaviour I don't really
care to deal with; but it is due to duplication of the environment.

PS accepts a wide variety of display modes, because the Postscript
language is by nature pixel\index{pixel}-independent while BGI is pixel-oriented;
and the lines' width, points\index{point}' size\index{size!points} etc. are determined by the
device's resolution. There are 6 normal modes\index{mode!PS}, and 6 encapsulated\index{PostScript!Encapsulated} modes.
The former create output ready to send to a printer\index{printer}, while the latter
are best suited to create images to be inserted in a document.

There is an eternal problem with color and display versus hardcopy. The
colors are not changed, but the greytones are swapped. This is logical since
a screen is black by default, while a blank sheet of paper is white.
The driver accepts the same color requests as a \svga\ card: 16 colors by
default and a user-settable 256-entry palette\index{palette}. Here are the
first preset 16 colors:
\begin{center}
\begin{tabular}{rlrrr}
{\bf Index}	& {\bf Color}	& {\bf Red}	& {\bf Green}	& {\bf Blue} \\[1mm]
0	& White	& 100\%	& 100\%	& 100\% \\
1	& Dark Blue	& 0\%	& 0\%	& 50\% \\
2	& Dark Green	& 0\%	& 50\%	& 0\% \\
3	& Dark Cyan	& 0\%	& 50\%	& 50\% \\
4	& Dark Red	& 50\%	& 0\%	& 0\% \\
5	& Dark Magenta	& 50\%	& 0\%	& 50\% \\
6	& Dark Brown	& 50\%	& 50\%	& 0\% \\
7	& Dark Grey	& 50\%	& 50\%	& 50\% \\
8	& Light Grey	& 75\%	& 75\%	& 75\% \\
9	& Blue	& 0\%	& 0\%	& 100\% \\
10	& Green	& 0\%	& 100\%	& 0\% \\
11	& Cyan	& 0\%	& 100\%	& 100\% \\
12	& Red	& 100\%	& 0\%	& 0\% \\
13	& Magenta	& 100\%	& 0\%	& 100\% \\
14	& Brown	& 100\%	& 100\%	& 0\% \\
15	& Black	& 0\%	& 0\%	& 0\% \\
\end{tabular}
\end{center}
If your printer has no color capabilities, these values are converted to
greytones by combining linearly the RGB percentages.

\begin{center}
\begin{tabular}{rlll}
\multicolumn{1}{c}{{\bf Mode}}	& \multicolumn{1}{c}{{\bf Type}}
	& \multicolumn{1}{c}{{\bf Resolution\index{resolution}}}
	& \multicolumn{1}{c}{{\bf Page Size\index{size!page (PS)} [inches]}} \\[2mm]
0	& Postscript	& $100\times100$	& $7\times7$ \\
1	& Postscript	& $320\times200$	& $11.2\times7$ \\
2	& Postscript	& $640\times480$	& $9.333\times7$ \\
3	& Postscript	& $1024\times768$	& $9.333\times7$ \\
4	& Postscript	& $1024\times1024$	& $7\times7$ \\
5	& Postscript	& $2048\times2048$	& $7\times7$ \\
6	& Encapsulated	& $100\times100$	& $7\times7$ \\
7	& Encapsulated	& $320\times200$	& $11.200\times7$ \\
8	& Encapsulated	& $640\times480$	& $9.333\times7$ \\
9	& Encapsulated	& $1024\times768$	& $9.333\times7$ \\
10	& Encapsulated	& $1024\times1024$	& $7\times7$ \\
11	& Encapsulated	& $2048\times2048$	& $7\times7$ \\
\end{tabular}
\end{center}
An example of PS can be seen in the Hershey\index{hershey} sample code.
PS has been used there to insert sample displays in a \TeX\index{TEX@\TeX} document.

There are no restrictions nor royalties associated to the use, distibution
or modification of PS and SPY.

\newpage
\chapter{\pcs\ BGI primitives reference}\label{reference}
This section is a list of recognized BGI primitives, by category. In each
category, they are sorted by ``logical'' order, that is,
the simplest is at the beginning and the most seldom used or complex at the end.
Essential procedures are marked with a harpoon ($\hookleftarrow$)
in the margin.
Optional parameters\index{arguments!optional} are enclosed in square brackets ([\kern2pt]).

Color\index{color}, video modes\index{modes} and some other types of parameters for which symbols\index{symbols!and numbers} are
listed in this list can be entered either as symbol or as
the corresponding number;
numbers exist only for BGI compatibility,
but you should only use symbols, as they are more ``human''.
When a function such as {\tt GET-TEXT-SETTINGS\ttindex{GET-TEXT-SETTINGS}} is used,
a symbol is returned. The only exceptions are {\tt GET-COLOR\ttindex{GET-COLOR}}
which returns a number to avoid confusion when re-mapping
the palette\index{palette}, and {\tt GET-GRAPH-MODE\ttindex{GET-GRAPH-MODE}} because the corresponding symbol
depends on the currently loaded driver and might
be not available when using an user-installed driver.
Equivalence tables can be found in the {\tt BGI-ENVIRONMENT}.

\section{The Graphics Control System}
\esfunc{INIT-GRAPH}{\opt{driver \opt{graph-mode \opt{path-for-BGI-files}}}\index{path (BGI)}}\ttindex{INIT-GRAPH}
	Init-graph loads the BGI driver into memory, initialize all to the
	defaults values and turn the graphic device into graphic mode.
	{\it You cannot issue any graphic command prior to calling}
	{\tt INIT-GRAPH}. In addition to these standard operations,
	\pcs\ also reduces the \SY{CONSOLE}\/ window to the bottom
	4 lines of screen, i.e.\ calls {\tt (SPLIT-SCREEN 4)}.
	Use {\tt (FULL-SCREEN)} to use the whole text screen.

	{\it Driver} can be any symbol\index{symbol!driver} returned by {\tt INSTALL-USER-DRIVER\ttindex{INSTALL-USER-DRIVER}},
	or one of the following:
	\begin{multicols}{4}
	\begin{flushleft}
	\SY{DETECT} \\
	\SY{CGA} \\
	\SY{MCGA} \\
	\SY{EGA} \\
	\SY{EGA64} \\
	\SY{EGAMONO} \\
	\SY{IBM8514} \\
	\SY{HERCMONO} \\
	\SY{ATT400} \\
	\SY{VGA} \\
	\SY{PC3270}
	\end{flushleft} 
	\end{multicols}

	\SY{DETECT} causes auto-detection\index{auto-detection} of graphic hardware.
	It works only for all the original Borland\index{Borland} drivers except \ibm.

	The {\it graph-mode} range depends of the BGI driver.
	It can be obtained using {\tt the GET-MAX-MODE\ttindex{GET-MAX-MODE}} primitive (see below).
	You can use the following symbols, or a valid number:
	\addtocounter{footnote}{1}\footnotetext{if 256{\sc K} on board}\addtocounter{footnote}{-1}
	\begin{multicols}{2}
	\begin{tabbing}
	\Sy{HERCMONO-HIxxx} \= \kill
	\SY{CGA-C0}	\> $320\times200$, 4 colors\index{color} \\
	\Sy{CGA-C1}	\> $320\times200$, 4 colors \\
	\Sy{CGA-C2}	\> $320\times200$, 4 colors \\
	\Sy{CGA-C3}	\> $320\times200$, 4 colors \\
	\SY{CGA-HI}	\> $640\times200$, 2 colors \\[1mm]
	\SY{MCGA-C0}	\> $320\times200$, 4 colors \\
	\Sy{MCGA-C1}	\> $320\times200$, 4 colors \\
	\Sy{MCGA-C2}	\> $320\times200$, 4 colors \\
	\Sy{MCGA-C3}	\> $320\times200$, 4 colors \\
	\SY{MCGA-MED}\> $640\times200$, 2 colors \\
	\SY{MCGA-HI}	\> $640\times480$, 2 colors \\[1mm]
	\SY{ATT400-C0}	\> $320\times200$, 4 colors \\
	\Sy{ATT400-C1}	\> $320\times200$, 4 colors \\
	\Sy{ATT400-C2}	\> $320\times200$, 4 colors \\
	\Sy{ATT400-C3}	\> $320\times200$, 4 colors \\
	\SY{ATT400-MED}	\> $640\times200$, 2 colors \\
	\SY{ATT400-HI}	\> $640\times400$, 2 colors \\[1mm]
	\SY{EGA-LO}	\> $640\times200$, 16 colors, 4 pages\index{page} \\
	\SY{EGA-HI}	\> $640\times350$, 16 colors, 2 pages \\
	\SY{EGA64-LO}\> $640\times200$, 16 colors \\
	\SY{EGA64-HI}\> $640\times350$, 16 colors \\
	\SY{EGAMONO-HI}\> $640\times350$, 2 colors, 2 pages\footnotemark \\
	\SY{VGA-LO}	\> $640\times200$, 16 colors, 2 pages \\
	\SY{VGA-MED}	\> $640\times350$, 16 colors, 2 pages \\
	\SY{VGA-HI}	\> $640\times480$, 16 colors \\[1mm]
	\SY{HERCMONO-HI}	\> $720\times348$, 2 colors, 2 pages \\
	\SY{PC3270-HI}	\> $720\times350$, 2 colors \\
	\SY{IBM8514-LO}	\> $1024\times768$, 256 colors \\
	\SY{IBM8514-HI}	\> $640\times480$, 256 colors
	\end{tabbing}
	\end{multicols}
	\Sy{CGA-C}$\langle n \rangle$ are modes with same resolution\index{resolution}
	but different palettes\index{palette!CGA}:
	\begin{itemize}
	\item	Mode\index{mode!CGA} 0 allows {\itt BACKGROUND, LIGHT-GREEN, LIGHT-RED {\rm and} YELLOW}
	\item	Mode 1 allows {\itt BACKGROUND, LIGHT-CYAN, LIGHT-MAGENTA {\rm and} WHITE}
	\item	Mode 2 allows {\itt BACKGROUND, GREEN, RED {\rm and} BROWN}
	\item	Mode 3 allows {\itt BACKGROUND, CYAN, MAGENTA {\rm and} LIGHT-GRAY}
	\end{itemize}
	This is true for \Sy{MCGA-C}$\langle n \rangle$ and
	\Sy{ATT400-C}$\langle n \rangle$ too.

	The default values are:
	\begin{center}
	\begin{tabular}{ll}
	{\it driver} & \SY{DETECT} \\
	{\it mode} & Best colors\index{color}, best resolution \\
	{\it path-for-BGI-files} & {\tt PCS-SYSDIR\index{PCS-SYSDIR}}, the directory containing {\tt BOOTSTRP.APP\index{BOOTSTRP.APP}}
	\end{tabular}
	\end{center}

\esfunc{SET-WRITE-MODE}{wmode}\index{mode!write}\ttindex{SET-WRITE-MODE}
	This global setting allows you to choose what to do when drawing
	overwrite a previously plotted object.

	{\it Wmode} can be one of the following:
	\begin{tabbing}
	\SY{COPY} (this is the default) \\
	\SY{XOR}
	\end{tabbing}
	
	This function currently works only for lines, rectangles, polygons\index{polygon}
	and text. {\tt PUT-IMAGE\ttindex{PUT-IMAGE}} has his own setting,
	with other possible modes.

\esthunk{RESTORE-CRT-MODE}
	This brings the display back to the text mode when {\tt INIT-GRAPH\ttindex{INIT-GRAPH}} was
	used, but doesn't unload BGI drivers from memory. It is useful with
	{\tt SET-GRAPH-MODE\ttindex{SET-GRAPH-MODE}} to toggle between graphic and text mode.

\esfunc{SET-GRAPH-MODE}{\opt{mode}}\index{mode}
	This changes the current video mode to the one given as parameter.
	Correct values are listed under {\tt INIT-GRAPH\ttindex{INIT-GRAPH}}, or can be obtained
	by a call to {\tt GET-MAX-MODE\ttindex{GET-MAX-MODE}}. {\tt SET-GRAPH-MODE} can be used with 
	{\tt RESTORE-CRT-MODE\ttindex{RESTORE-CRT-MODE}} to toggle between graphics and text.

	The default value for {\it mode} is the previously used graph mode.

\esthunk{CLOSE-GRAPH}
	This turns the video adapter back to text mode, and unloads the
	driver from	memory.
	{\it You should always use {\tt CLOSE-GRAPH} at the end of your
	graph programs,} or you have risks to load another
	copy of BGI driver into memory each	time you start it,
	which would cause sooner or later a fatal out-of-memory error.

\thunk{GRAPH-DEFAULTS}
	This resets all graphics settings to their default values:
	\begin{itemize}
	\item	Sets the viewport\index{viewport} to entire screen
	\item	Moves the pen\index{pen} to upper left corner
	\item	Sets the default colors\index{color} and palette
	\item	Sets all default style, patterns, text fonts and justification
	\end{itemize}

\thunk{DETECT-GRAPH}
 	Tries to recognize the video hardware present in the computer,
	and returns the detected adapter with the best
	mode available. See the list of adapters and modes
	under {\tt INIT-GRAPH}. The returned driver and mode
	(in a pair) can be used to find out what would be the result of a
	call to {\tt (INIT-GRAPH \SY{DETECT})}.
	User drivers and \SY{IBM8514} cannot be auto-detected.

\func{GET-MODE-RANGE}{\opt{driver}}
	Returns the range of values acceptable as graphics mode for a given
	video hardware. If {\it driver} is not valid,
	returns \Sy{(-1 .\ -1)}; otherwise returns a pair
	made of the smallest and the largest mode.

	This works with Borland\index{Borland} ``factory'' drivers only.
	Preferably use {\tt GET-MAX-MODE\ttindex{GET-MAX-MODE}}.

	The default value for {\it driver} is the current driver.

\thunk{GET-GRAPH-MODE}
	Returns the current graphic mode number. Can be used with
	{\tt SET-GRAPH-MODE\ttindex{SET-GRAPH-MODE}} to remember and restore
	the video mode from a session to the other,
	but should be used carefully in order to maintain
	device-independence of programs.

\func{INSTALL-USER-DRIVER}{name}\index{driver!user-supplied}
	Installs the driver whose name is specified as user BGI driver.
	The HP95LX driver should be used this way, since it is not part
	of the standard BGI drivers. {\tt INSTALL-USER-DRIVER} establishes
	a link between the driver and the list of known drivers.
	It returns a symbol, made of name, which can then be used
	when calling {\tt INIT-GRAPH}. The argument {\it name} is a string.
	
\func{INSTALL-USER-FONT}{name}\index{font!user-supplied}
	Installs the font whose name is specified as user font, and returns
	its symbolic equivalent in same manner as {\tt INSTALL-USER-DRIVER}.

\section{Drawing}
\esfunc{LINE}{start-point end-point}
	Draws a line using current color, line-style and write-mode.
	{\it Start-point} and {\it end-point} are points for the current
	coordinate system, i.e.\ pairs by default.

\esfunc{RECTANGLE}{upper-left-point lower-right-point}
	Draws an empty rectangle using current color, line-style, write-mode.

\esfunc{DRAW-POLY}{list-of-points}
	Draws a polygon, i.e.\ lines from points to points. If you want the
	polygon to be closed, you need to put the first point again at the
	end of the list.

\esfunc{CIRCLE}{center-point radius}
	Draws a circle using current color and thickness (part of line-style).
	If your circles look oval, use {\tt SET-ASPECT-RATIO\ttindex{SET-ASPECT-RATIO}} to correct them.

\func{ARC}{center-point start-angle end-angle radius}
	Draws an arc of circle using color and thickness (see {\tt CIRCLE}).
	Angles are given in degrees\index{degrees}\index{angles}, using whole numbers. {\tt ARC\ttindex{ARC}} returns
	the coordinates of the arc as {\tt GET-ARC-COORDS\ttindex{GET-ARC-COORDS}} would have do it.

\func{ELLIPSE}{center-point start-angle end-angle distances}\index{distance}
	Exactly the same as {\tt ARC}, but distances is a pair of X and Y radius.
	To draw a whole ellipse, let $ \mbox{\it start-angle} = 0$
	and $\mbox{\it end-angle} = 360$\index{angles}.

\thunk{GET-ARC-COORDS}
	Returns a list of three points: the center-point of the last arc
	drawn, the starting-point and the ending-point (i.e.\ 3 pairs).
	This command is useful if you want to join lines and arc curves.

\func{SET-ASPECT-RATIO}{factor}
	{\it Factor} is a pair of integers $p$ and $q$ representing
	a rational number, $p/q$,
	a coefficient by which the radius is multiplied to obtain the
	y-radius when drawing a circle or an arc. Use this function either
	to adjust circles when your video adapter makes circles oval, or
	to draw ellipses of given proportion but of different sizes.

\thunk{GET-ASPECT-RATIO}
	Returns the factor as described in {\tt SET-ASPECT-RATIO}.

\esfunc{SET-LINE-STYLE}{line-style user-pattern thickness}\index{thickness}\index{lines!user-defined}
	Sets the line drawing parameters: style and width. 
	If {\it line-style} is \SY{USER-BIT}, {\it user-pattern}
	is a 16-bit integer specifying the pattern used to draw
	straight lines. For instance, a	user-defined pattern of
	\verb+#b1110001110001010+ would draw
	``\/\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}%
		\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}%
		\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{2.1mm}{0.7mm}\rule[1ex]{2.1mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}%
		\rule[1ex]{0.7mm}{0.7mm}\rule[1ex]{0.7mm}{0mm}''.

	Line-style is one of the following:
	\begin{multicols}{4}
	\begin{flushleft}
	\SY{SOLID} \\
	\SY{DOTTED} \\
	\SY{CENTER} \\
	\SY{DASHED} \\
	\SY{USER-BIT}
	\end{flushleft}
	\end{multicols}

	Thickness can be any positive integer, and in particular:
	\begin{center}
	\begin{tabbing}
	\SY{NORMAL}	\= which is 1 \\
	\SY{THICK}	\> which is 3
	\end{tabbing}
	\end{center}
	Other values are not illegal, but do not necessarily produce different
	results.

\thunk{GET-LINE-SETTINGS}
	Returns the list made of the three settings
	described in {\tt SET-LINE-STYLE}.

\func{MOVE-TO}{point}
	Moves the ``pen\index{pen}'' to the given position, without changing anything
	on the screen.

\func{LINE-TO}{point}
	Draws a line from the current ``pen\index{pen}'' position to {\it point},
	using the current line style, color and thickness

\func{MOVE-REL}{distances\index{distance}}
	Same as {\tt MOVE-TO\ttindex{MOVE-TO}}, except the move is done relatively to
	the current pen\index{pen} position.

\func{LINE-REL}{distances}
	You make a soup with {\tt LINE-TO\ttindex{LINE-TO}} and {\tt MOVE-REL\ttindex{MOVE-REL}} and
	you'll get it right.

\section{Filling}\index{filling}
\esfunc{FLOOD-FILL}{start-point stop-color}\index{color!stop}
	Fills a region of the screen starting from start-point until
	{\it stop-color} is encountered. When used with open shapes, the whole
	screen might get filled.

	{\tt FLOOD-FILL} is not yet supported for \ibm\ and
	\hp\ drivers. Where possible, avoid using {\tt FLOOD-FILL}.

\esfunc{BAR}{upper-left-point lower-right-point}
	Draws a solid 2-dimensional bar without outlet, using the current
	fill pattern and fill color.

\func{BAR-3D}{upper-left-point lower-right-point depth\index{depth} top?}\index{top}
	Draws a solid 3-dimensional bar with outlets, using the current fill
	pattern and fill color for the front face, and current line width and
	color for outlet. {\it Depth} is the 3rd dimension, given in the
	X-dimension coordinate system. {\it Top?} is \verb+#T+ if a top
	should be drawn, and \verb+#F+ if not. \verb+#T+ and \verb+#F+
	can be replaced by 1 and 0). This function is very useful for
	drawing bar charts\index{charts}.

\func{FILL-POLY}{list-of-points}
	Draws a filled polygon\index{polygon} using the current fill pattern and color.
	See {\tt DRAW-POLY}.

\esfunc{FILL-ELLIPSE}{center-point distances\index{distance}}
	Draws a filled ellipse using the current fill pattern and color.

\func{PIE-SLICE}{center-point start-angle end-angle radius}
	Fills a slice of pie. Angles are given in degrees.
	Use {\tt SET-ASPECT-RATIO\ttindex{SET-ASPECT-RATIO}} if your pie looks sad.

\func{SECTOR}{center-point start-angle end-angle distances}
	Draws a slice of a filled ellipse using current fill pattern and fill
	color (most general function).
   
\esfunc{SET-FILL-STYLE}{fill-style color}\index{color!fill}
	Sets the current fill pattern to one of the defined pattern and selects
	the fill color. {\it Fill-style} can be one of the following:
	\begin{center}
	\begin{tabular}{lll}
	\SY{EMPTY}		& \multicolumn{2}{l}{all background color} \\
	\SY{SOLID}		& \multicolumn{2}{l}{all fill color} \\
	\SY{LINE}		& continuous	&
	\thicklines\begin{picture}(80,10)(0,0)\put(0,3){\line(1,0){80}}\end{picture} \\
	\SY{LTSLASH}		& light		&
	\thinlines\begin{picture}(80,10)(0,0)\multiput(0,0)(10,0){8}{\line(1,1){10}}\end{picture} \\
	\SY{SLASH}		& thick		&
	\thicklines\begin{picture}(80,10)(0,0)\multiput(0,0)(8,0){10}{\line(1,1){10}}\end{picture} \\
	\SY{LTBKSLASH}	& light		&
	\thinlines\begin{picture}(80,10)(0,0)\multiput(0,10)(10,0){8}{\line(1,-1){10}}\end{picture} \\
	\SY{BKSLASH}		& thick		&
	\thicklines\begin{picture}(80,10)(0,0)\multiput(0,10)(8,0){10}{\line(1,-1){10}}\end{picture} \\
	\SY{HATCH}		& hatch		&
	\thicklines\begin{picture}(80,10)(0,0)\multiput(0,2)(0,6){2}{\line(1,0){80}}%
		\multiput(0,0)(6,0){14}{\line(0,1){10}}\end{picture} \\
	\SY{XHATCH}		& X-hatch	&
	\thicklines\begin{picture}(80,10)(0,0)\multiput(0,10)(8,0){10}{\line(1,-1){10}}%
		\multiput(0,0)(8,0){10}{\line(1,1){10}}\end{picture} \\
	\SY{INTERLEAVE}	& \multicolumn{2}{l}{50\% grey\index{grey!50\%}} \\
	\SY{CLOSE-DOT}	& \multicolumn{2}{l}{20\% grey\index{grey!20\%}} \\
	\SY{WIDE-DOT}	& \multicolumn{2}{l}{10\% grey\index{grey!10\%}} \\
	\SY{USER-FILL}	& \\
	\end{tabular}
	\end{center}
	Don't use {\tt (SET-FILL-STYLE \SY{USER-FILL} ...)},
	but use {\tt SET-FILL-PATTERN\ttindex{SET-FILL-PATTERN}} instead,
	or you might get unpredictable results.

	For a table of color constants, see {\tt SET-COLOR\ttindex{SET-COLOR}} below.

\esfunc{SET-FILL-PATTERN}{fill-pattern color}\index{color!fill}\index{pattern!user-defined}
	This call is similar to {\tt SET-FILL-STYLE\ttindex{SET-FILL-STYLE}}, except that it sets
	a user-defined pattern instead of a predefined one.
	A fill-pattern is an 8x8 matrix used to fill surfaces;
	at the \pcs	level, it is a list of 8-bit integers,
	each coding one row.
	Normally there will be 8 elements in the list but if you put less,
	PCS will assume you want to repeat periodically the given ones.
	For example, the chain pattern
	\begin{center}
	\begin{flushleft}
	\verb+(SET-FILL-PATTERN '(#b01000100+ \\
	\verb+                    #b00111000+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b00111000+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b01000100)+ \SY{BLUE}{\tt )}
	\end{flushleft}
	\end{center}
	will produce the same result as
	\begin{center}
	\begin{flushleft}
	\verb+(SET-FILL-PATTERN '(#b00111000+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b01000100+ \\
	\verb+                    #b01000100)+ \SY{BLUE}{\tt )}
	\end{flushleft}
	\end{center}

\thunk{GET-FILL-SETTINGS}
	This returns a pair containing the standard fill style number
	and the fill color. If the fill style number is 12 (\SY{USER-FILL}),
	you can issue a call to {\tt GET-FILL-PATTERN\ttindex{GET-FILL-PATTERN}} to get the exact pattern.

\thunk{GET-FILL-PATTERN}
	This returns a string containing the fill pattern.

\section{Bitmapping\index{bitmapping}}
\esthunk{CLEAR-DEVICE}
	Fills the whole screen with the background color and moves the
	pen\index{pen} to the upper-left corner.

\esfunc{PUT-PIXEL}{point color}\index{plot}\index{pixel}
	Plots a single pixel at coordinates specified by point, using
	the desired color (see {\tt SET-COLOR\ttindex{SET-COLOR}} below for color names).

\esfunc{GET-PIXEL}{point}
	Returns the color number of the selected pixel.

\esfunc{GET-IMAGE}{upper-left-point lower-right-point}
	Returns an image-string containing all bitmap data for the rectangle
	enclosed between the two given points\index{point}. Don't try to look at too
	big strings of this type, or you might have to wait for a long
	time until you reach the end, especially if there is a bell every
	two chars\ldots

	You should use {\tt IMAGE-SIZE\ttindex{IMAGE-SIZE}} to figure out how much memory a bitmap
	needs, and never allocate an image of 32Kb or more.

\esfunc{PUT-IMAGE}{new-upper-left-point image-string put-mode}
	Rewrites\index{rewrite} (very quickly!) the whole image saved in image-string, with
	the upper left corner at {\it new-upper-left-point}.
	You can use various	displaying methods:
	\begin{multicols}{5}
	\begin{flushleft}
	\SY{COPY} \\
	\SY{XOR} \\
	\Sy{OR} \\
	\Sy{AND} \\
	\Sy{NOT} \\
	\end{flushleft}
	\end{multicols}
	This function can be used to animate\index{animate} a small shape on the screen.

\func{IMAGE-SIZE}{upper-left-point lower-right-point}
	Returns the size in bytes required to store the bitmap enclosed
	between the two given points.

\func{SET-VIEWPORT}{upper-left-point lower-right-point clip?\index{clipping}}\index{viewport}
	Translates the coordinate system so that the coordinates of screen
	upper-left corner before a call are the same as the coordinates of
	upper-left-point after the call; moves the pen\index{pen} to this point;
	if {\it clip?} is \verb+#T+ or 1, clip all incoming function calls
	to the rectangle between the two points (i.e.\ no drawing will 
	occur outside of this zone).

	The redefinition of viewport is always relative to the whole
	screen, using the global (user- or not) coordinates system.

\thunk{CLEAR-VIEWPORT}
	Fills the active viewport with the background color and moves the pen\index{pen}
	to the upper left corner of the viewport.

\thunk{GET-VIEW-SETTINGS}
	Returns the list of {\tt SET-VIEWPORT\ttindex{SET-VIEWPORT}}'s three parameters
	(where {\it clip?} is either 1 or 0).

\func{SET-ACTIVE-PAGE}{page}\index{page!active}
	For graphic adapters which support more than one page (see the table
	at {\tt INIT-GRAPH\ttindex{INIT-GRAPH}}), this functions allows one to choose on which page
	the next drawings should have effect.

	It doesn't have to be the visual page, so one can draw off-screen and
	then bring the prepared page using just one command (see 
	{\tt SET-VISUAL-PAGE}).

\func{SET-VISUAL-PAGE}{page}\index{page!visual}
	For graphic adapters which support more than one page
	this functions allows one to choose which page is
	to be displayed on the screen. 

	It doesn't have to be the active page, so one can draw off-screen and
	then bring the prepared page using just one command (see 
	{\tt SET-ACTIVE-PAGE}).

\section{Writing text}\index{writing}
\esfunc{OUT-TEXT-XY}{start-point text-string}
	Writes {\it text-string} starting from {\it start-point} according to
	current justification (see {\tt SET-TEXT-JUSTIFY\ttindex{SET-TEXT-JUSTIFY}}) and text style (see
	{\tt SET-TEXT-STYLE\ttindex{SET-TEXT-STYLE}}). The current color and write mode are used.

\func{OUT-TEXT}{text-string}
	Writes {\it text-string} starting at the current pen\index{pen} position,
	according to current justification, style, color and write mode.
	If the current direction is \SY{HORIZ} and the
	text justification is \SY{LEFT},	the pen\index{pen} is
	moved to the right of the text; otherwise, it is left unchanged.

\esfunc{SET-TEXT-STYLE}{font direction size}\index{text!direction}\index{font}\index{text!font}\index{text!size}
	Sets text appearance properties. {\it Font} 
	can be either a number returned
	by {\tt INSTALL-USER-FONT\ttindex{INSTALL-USER-FONT}} or one of the following,
	where \SY{DEFAULT} is the only bit-mapped font:
	\begin{multicols}{4}
	\begin{flushleft}
	\SY{DEFAULT} \\
	\SY{TRIPLEX}	\\
	\SY{SMALL} \\
	\SY{SANS-SERIF} \\
	\SY{GOTHIC} \\
	\SY{SCRIPT} \\
	\SY{SIMPLEX} \\
	\SY{TRIPLEX-SCR} \\
	\SY{COMPLEX} \\
	\SY{EUROPEAN} \\
	\SY{BOLD}
	\end{flushleft}
	\end{multicols}
	{\it Direction} is \SY{HORIZ} or \SY{VERT}.

	{\it Size} is either a number from 1 to 10, or 0 for the default size.
	The default size will produce a size of 4, but will also enable user 
	character sizes (see {\tt SET-USER-CHAR-SIZE\ttindex{SET-USER-CHAR-SIZE}} below).

\esfunc{SET-TEXT-JUSTIFY}{horiz-just vert-just}\index{justification}
	Choose where to align the text. {\it Horiz-just} is one of the following:
	\begin{center}
	\SY{LEFT} \hspace{2cm}
	\SY{CENTER} \hspace{2cm}
	\SY{RIGHT} \hspace{2cm}
	\end{center}
	{\itt Vert-just} is one of the following:
	\begin{center}
	\SY{BOTTOM} \hspace{2cm}
	\SY{CENTER} \hspace{2cm}
	\SY{TOP} \hspace{2cm}
	\end{center}
	For example, \SY{LEFT} means that the starting-point is on the top
	left edge of the text.

\thunk{GET-TEXT-SETTINGS}
	Returns a list of the five text settings: font, direction, size, 
	horizontal and vertical justification.

\func{SET-USER-CHAR-SIZE}{x-ratio y-ratio}
	When {\it font-size} is set to 0, this allows you to give the font any
	width and height. The font's X and Y sizes are multiplied by the
	x- and y-ratios. Ratios\index{ratios} are rational numbers, i.e.\ pairs of integers.

\esfunc{TEXT-SIZE}{text-string}
	Returns a pair containing the width and height of {\it text-string}
	using the current font.
	It doesn't care about text direction. 
	The height is independent of the character written, i.e.\ an ``I'' has
	the same height as an ``x''.

\section{Using Color}\index{color}
\esfunc{SET-COLOR}{color}
	Sets the current color for all drawing functions.
	If you are have 16 or more colors, {\it color}
	can be one of the following:
	\begin{center}
	\begin{tabular}{lr}
	{\bf Symbol} & \multicolumn{1}{c}{{\bf Equivalent number}} \\[1mm]
	\SY{BLACK}	& 0 \\
	\SY{BLUE}	& 1 \\
	\SY{GREEN}	& 2 \\
	\SY{CYAN}	& 3 \\
	\SY{RED}	& 4 \\
	\SY{MAGENTA}	& 5 \\
	\SY{BROWN}	& 6 \\
	\SY{LIGHT-GRAY}	& 7 \\
	\SY{DARK-GRAY}	& 8 \\
	\SY{LIGHT-BLUE}	& 9 \\
	\SY{LIGHT-GREEN}	& 10 \\
	\SY{LIGHT-CYAN}	& 11 \\
	\SY{LIGHT-RED}	& 12 \\
	\SY{LIGHT-MAGENTA}	& 13 \\
	\SY{YELLOW}	& 14 \\
	\SY{WHITE}	& 15 \\
	\end{tabular}
	\end{center}
	If you are using \cga, \mcga\ or \att\ four-color modes,
	you should use instead the following constants,
	depending on your palette:
	\begin{center}
	\begin{tabular}{rllll}
	0 & \SY{BACKGROUND}	& \SY{CGA-LIGHT-GREEN}	& \SY{CGA-LIGHT-RED}	& \SY{CGA-YELLOW} \\
	1 & \SY{BACKGROUND}	& \Sy{CGA-LIGHT-CYAN}	& \SY{CGA-LIGHT-MAGENTA}	& \SY{CGA-WHITE} \\
	2 & \SY{BACKGROUND}	& \Sy{CGA-GREEN}	& \SY{CGA-RED}	& \SY{CGA-BROWN}	\\
	3 & \SY{BACKGROUND}	& \Sy{CGA-CYAN}	& \SY{CGA-MAGENTA}	& \SY{CGA-LIGHT-GRAY} \\
	\end{tabular}
	\end{center}
	You can change the effect of {\tt SET-COLOR} using {\tt SET-PALETTE\ttindex{SET-PALETTE}}.
	With \cga-style adapters, only the first color (i.e.\ black, the
	background color) can be changed (it is best to use {\tt SET-BK-COLOR\ttindex{SET-BK-COLOR}}).

	If you totally re-map the palette with a \ega\ or \vga\ adapter, 
	use {\tt SET-COLOR} with numbers rather than with symbols, since it
	doesn't make programs very clear when
	{\tt (SET-COLOR \Sy{BLUE}\ittindex{BLUE})} turns color
	to green for example\ldots

\esfunc{SET-BK-COLOR}{color}
	Sets the background color to the specified color.
	{\it Color} can be any of the following (for \cga-likes too):
	\begin{center}
	\begin{tabular}{lr}
	{\bf Symbol} & \multicolumn{1}{c}{{\bf Equivalent number}} \\[1mm]
	\SY{BLACK}	& 0 \\
	\SY{BLUE}	& 1 \\
	\SY{GREEN}	& 2 \\
	\SY{CYAN}	& 3 \\
	\SY{RED}	& 4 \\
	\SY{MAGENTA}	& 5 \\
	\SY{BROWN}	& 6 \\
	\SY{LIGHT-GRAY}	& 7 \\
	\SY{DARK-GRAY}	& 8 \\
	\SY{LIGHT-BLUE}	& 9 \\
	\SY{LIGHT-GREEN}	& 10 \\
	\SY{LIGHT-CYAN}	& 11 \\
	\SY{LIGHT-RED}	& 12 \\
	\SY{LIGHT-MAGENTA}	& 13 \\
	\SY{YELLOW}	& 14 \\
	\SY{WHITE}	& 15 \\
	\end{tabular}
	\end{center}

	On \cga-ish and \ega\ systems, {\tt SET-BK-COLOR} only changes the entry 0
	of the palette.

	If you totally re-map the palette with a \ega\ or \vga\ adapter, 
	use {\tt SET-BK-COLOR} with numbers rather than symbols.

\thunk{GET-COLOR}
	Returns current color number (not symbol, since a palette change
	would mix-up everything).

\thunk{GET-BK-COLOR}\index{color!background}
	Returns current background color number.

\esthunk{GET-MAX-COLOR}\index{color!maximal}
	Returns the number of the greatest acceptable color for current video
	mode (i.e.\ \#-of-colors minus 1).

\func{SET-PALETTE}{entry color}\ttindex{palette}
	Re-map the given entry of the palette to the specified color.
	It is useful for \ega\ and \vga\ (for \cga, it works only with entry 0,
	i.e.\ background color).
	{\it Entry} is an integer between 0 and {\tt (GET-PALETTE-SIZE)},
	and {\it color} is an integer between 0 and a constant depending
	on the hardware device.
	The following constants are defined:
	\begin{center}
	\begin{tabular}{lrl}
	{\bf Symbol} & \multicolumn{2}{c}{{\bf Equivalent number}} \\[1mm]
	\SY{EGA-BLACK}	& 0	& (\verb+#b000000+) \\
	\SY{EGA-BLUE}	& 1	& (\verb+#b000001+) \\
	\SY{EGA-GREEN}	& 2	& (\verb+#b000010+) \\
	\SY{EGA-CYAN}	& 3 \\
	\SY{EGA-RED}		& 4	& (\verb+#b000100+) \\
	\SY{EGA-MAGENTA}	& 5 \\
	\SY{EGA-LIGHT-GRAY}	& 7 \\
	\SY{EGA-BROWN}		& 20 \\
	\SY{EGA-DARK-GRAY}	& 56 \\
	\SY{EGA-LIGHT-BLUE}	& 57	& (\verb+#b001001+) \\
	\SY{EGA-LIGHT-GREEN}	& 58	& (\verb+#b010010+) \\
	\SY{EGA-LIGHT-CYAN}	& 59 \\
	\SY{EGA-LIGHT-RED}	& 60	& (\verb+#b100100+) \\
	\SY{EGA-LIGHT-MAGENTA}	& 61 \\
	\SY{EGA-YELLOW}		& 62 \\
	\SY{EGA-WHITE}		& 63	& (\verb+#b111111+) \\
	\end{tabular}
	\end{center}

	These are the values of the standard \ega\ and \vga\ palette. With
	these adapters, the following code would be equivalent to
	{\tt (SET-ALL-PALETTE (GET-DEFAULT-PALETTE))}:
	\begin{center}
	\begin{minipage}{10cm}
	\begin{flushleft}
	{\tt (SET-PALETTE \SY{BLACK} \SY{EGA-BLACK})} \\
	{\tt (SET-PALETTE \SY{BLUE} \SY{EGA-BLUE})} \\
	{\tt (SET-PALETTE \SY{RED} \SY{EGA-RED})} \\
	{\tt (SET-PALETTE \SY{GREEN} \SY{EGA-GREEN})} \\
	\ldots\\
	{\tt (SET-PALETTE \SY{WHITE} \SY{EGA-WHITE})} \\
	\end{flushleft}
	\end{minipage}
	\end{center}
	{\tt SET-PALETTE} doesn't works with the \ibm.
	Use {\tt SET-RGB-PALETTE\ttindex{SET-RGB-PALETTE}} instead.

\func{SET-RGB-PALETTE}{entry red green blue}\ttindex{palette!RGB}\index{color!RGB}
	This function has the same effect as {\tt SET-PALETTE}, except that it
	works only with the \vga~{\sc 256k}, the \ibm,
	and the \svga\ adapters.
	{\it Red}, {\it green} and {\it blue} are the strength of
	each color component. The 6 most significants bits of
	the least significant byte are used.

\func{SET-ALL-PALETTE}{color-list}\index{color!palette}
	{\it Color-list} is a list of length {\tt (GET-PALETTE-SIZE)}.
	This remaps all colors at the same time.
	There is no ``entry'' parameter	as there was with {\tt SET-PALETTE},
	since all colors are re-mapped in the normal order.

\thunk{GET-PALETTE}
	Returns a color-list corresponding to current palette.

\thunk{GET-DEFAULT-PALETTE}
	Returns a list with the default palette values.

\thunk{GET-PALETTE-SIZE}
	Returns the number of entries in the palette.

\section{Miscellaneous queries}
\esthunk{GET-MAX-XY}
	Returns the maximum screen coordinates {\it using pixel dimensions}.
	(1 unit = 1 pixel). It doesn't depend of {\tt SET-WORLD!} settings,
	so it can be used to determine the actual resolution\index{resolution} of
	the current video mode,
	in order to write your own coordinate conversion routine or to
	scan the screen pixel per pixel.

\thunk{GET-XY}
	Returns the current pen\index{pen} location.

\esthunk{GET-DRIVER-NAME}
	Returns the name of the currently loaded driver, without path and
	without its ".BGI"\index{BGI@.BGI} extension. When no driver is loaded, returns "".
	Can be used to know if a call to {\tt INIT-GRAPH\ttindex{INIT-GRAPH}} is necessary or not.
	A good startup code would be:
	\begin{center}
	\begin{minipage}{10cm}
	\begin{verbatim}
(if (= (GET-DRIVER-NAME) "")
    (INIT-GRAPH)
    (SET-GRAPH-MODE))
	\end{verbatim}
	\end{minipage}
	\end{center}
	Thus you can abort your program as often as you want, and restart
	it without filling the memory with copies of the graphics driver.

\func{GET-MODE-NAME}{mode}
	Returns a string corresponding to the real name of the specified video mode.

\thunk{GET-MAX-MODE}
	Returns the maximum possible value for the video mode for the BGI driver
	currently loaded in memory. The minimum value is 0.

\func{GRAPH-ERROR-MSG}{error-id}
	Returns the complete text message corresponding to a detected BGI
	error (actually used in the debugger; you shouldn't need it, except
	if you want to handle yourself BGI errors).

\thunk{GRAPH-RESULT}
	Returns the error-id corresponding to last BGI call. Use it with
	{\tt GRAPH-ERROR-MSG} to signal an error (already done for you).

\addcontentsline{toc}{part}{Index}
\printindex
\end{document}

